home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Source Code / Visual Basic Source Code.iso / vbsource / wlzhcxp2 / wlzhcxp.txt < prev    next >
Encoding:
Text File  |  1991-12-29  |  9.7 KB  |  250 lines
  1.             Visual Basic and C Advanced File Function Library.
  2.                           Ver 0.2 12/30/91
  3.  
  4. *--------------------------------------------------------------------------*
  5.  
  6.    This library was primarily written for use with Visual Basic, although C
  7. programmers may use it just as easily. Although these functions could be 
  8. done is pure Visual Basic, this library greatly increases the speed of the
  9. functions.
  10.    Compression is achieved using the LZH algorithm. Although somewhat slower
  11. than implode, it can obtain much better compression than implode. (Implode
  12. is the main compression used by ZIP.) Compression is dependent on the 
  13. amount of repetition in a file. If a file contains a large amount of the 
  14. same values of data, compression should be very good. Text and pictures with
  15. relatively large areas of a single color are good examples. Conversely, a 
  16. .COM file, usually very compact and not very repetious, are usually poorly
  17. compressed, sometimes by an insignificant amount. The tradeoff for the
  18. amount of compression achieved by the LZH algorithm is speed. It can take
  19. a while to compress a large file. 
  20.  
  21.    Library code was written for Microsoft C 6.00A. Data space consists of
  22. about 200 bytes. The data used for compression and decompression is
  23. dynamically allocated from the global heap. This means the calling program
  24. does not have to have a bloated data space and the data are may be marked
  25. as shared. Some code was written in assembler to prevent linking the
  26. standard C library, bloating the initial code segment to nearly 1000 bytes.
  27. As it stands, about 300 bytes in initially loaded, the rest only when called.
  28.  
  29.    This library is free to use by one and all AS LONG AS you agree not to
  30. hold me liable for and damage to hardware, software, firmware or your
  31. mental health by using this software. By using the library, the agreement is
  32. made. Otherwise, I would suggest you throw it away and pretend it never
  33. existed.
  34.  
  35.    Questions and suggestions made be made to me through the following by
  36. way of America Online, E-Mail to MarkG85.
  37.  
  38. *--------------------------------------------------------------------------*
  39.  
  40.    This version corrects a bug in the DeleteFile() function where the DS
  41. and DX register contents were reversed during an error condition. In
  42. addition, a simple Visual Basic program serves as an example of how to use
  43. the library in that environment.
  44.  
  45. *--------------------------------------------------------------------------*
  46.  
  47.    WLZHCXP.DLL is a Dynamic Linked Library (DLL) which provides additional
  48. functionality to a number of languages at very little cost to the program
  49. itself. GDI.EXE, USER.EXE and KRNL386.EXE are other examples of DLL files.
  50. To access this library, or any other, from Visual Basic, you must define
  51. the function names and the type of variables they expect to recieve and
  52. return. If the function definitions are incorrect, you are cheerfully told
  53. so by the smiling face of a UAE. Below are the definitions of functions
  54. available from this library and the types of variables they expect and
  55. return. Variables ending with a percent (%) sign are integers, those ending
  56. with an ampersand (&) are long integers and those ending in a dollar sign
  57. ($) are strings. A number of variables are filenames and thus require a
  58. string to be passed such as filename$ or "filename.ext". For more infor-
  59. -mation, see the Visual Basic example provided. And speaking of which...
  60.  
  61.    Examples are not my strong point and this one is no exception. To use
  62. the program, start by copying this file, WLZHCXP.TXT to your Visual Basic
  63. directory and press the "Compress" button which creates the file for the
  64. "Decompress" function. Next, run "Decompress" which creates the file for
  65. "Append", "Copy" and "Delete". After "Delete", you must again either "Copy"
  66. or "Decompress" to create the file WLZHCXP.OUT. Programming is straight-
  67. -forward and commented enough to figure out what's happening.
  68.  
  69. *--------------------------------------------------------------------------*
  70.  
  71. To use the library from Visual Basic, you must define the return constants 
  72. and functions in your Global Module as such:
  73.  
  74. Global Const LZH_OK = 0
  75. Global Const LZH_MEMERROR = 1
  76. Global Const LZH_NOTLZH = 2
  77. Global Const LZH_FILEERROR = 3
  78.  
  79. Global Const LZH_READONLY = 1
  80. Global Const LZH_HIDDEN = 2
  81. GLobal Const LZH_SYSTEM = 4
  82.  
  83. Declare Function Compress% LIB "wlzhcxp.dll" (ByVal InName$,ByVal OutName$)
  84. Declare Function Decompress% LIB "wlzhcxp.dll" (ByVal InName$,ByVal OutName$)
  85. Declare Function AppendFile% LIB "wlzhcxp.dll" (ByVal Dest$,ByVal File2$)
  86. Declare Function DeleteFile% LIB "wlzhcxp.dll" (ByVal Fname$)
  87. Declare Function GetFileSize& LIB "wlzhcxp.dll" (ByVal Fname$)
  88. Declare Function CopyFile% LIB "wlzhcxp.dll" (ByVal Srce$,ByVal Dest$)
  89. Declare Function GetFreeDiskSpace& LIB "wlzhcxp.dll" (ByVal Drv$)
  90. Declare Function SetFileStatus% LIB "wlzhcxp.dll" (ByVal Fname$, ByVal Status% )
  91.  
  92. *--------------------------------------------------------------------------*
  93.  
  94.    Using the library from C is considerably more flexible. For the sake of
  95. and example, I'll use the automatic runtime linking method:
  96.  
  97. *  SOURCE.H:
  98.  
  99. #define LZH_OK        0
  100. #define LZH_MEMERROR  1
  101. #define LZH_NOTLZH    2
  102. #define LZH_FILEERROR 3
  103.  
  104. int FAR PASCAL Compress( LPSTR, LPSTR );
  105. int FAR PASCAL Decompress( LPSTR, LPSTR );
  106. int FAR PASCAL AppendFile( LPSTR, LPSTR );
  107. int FAR PASCAL DeleteFile( LPSTR );
  108. long FAR PASCAL GetFileSize( LPSTR );
  109. int FAR PASCAL CopyFile( LPSTR, LPSTR );
  110.  
  111.  
  112. *  SOURCE.DEF
  113.  
  114. IMPORTS
  115.    Compress=WLZHCXP.2
  116.    Decompress=WLZHCXP.3
  117.    AppendFile=WLZHCXP.5
  118.    DeleteFile=WLZHCXP.6
  119.    GetFileSize=WLZHCXP.4
  120.    CopyFile=WLZHCXP.7
  121.    GetFreeDiskSpace=WLZHCXP.8
  122.  
  123. *  SOURCE.MAK
  124.  
  125. link /NOD SOURCE,,,SOURCE.EXE,MLIBCEW LIBW WLZHCXP,SOURCE.DEF
  126.  
  127. Note that the library was compiled and linked using the MEDIUM memory model.
  128.  
  129. *--------------------------------------------------------------------------*
  130.  
  131. Error codes:
  132.    LZH_OK:        Everything went OK, no errors.
  133.    LZH_MEMERROR:  A memory error occurred. Unable to continue operation.
  134.    LZH_NOTLZH:    File to be decompressed was not compressed.
  135.    LZH_FILEERROR: A file error occurred. Unable to continue operation.
  136.  
  137. *--------------------------------------------------------------------------*
  138.  
  139. Function listing:
  140.  
  141.  
  142. int FAR PASCAL Compress( LPSTR InName, LPSTR OutName )
  143.    Compresses data taken from source file, writing results to destination.
  144.  
  145.    Parameters:
  146.       InName:  Filename of source file to be compressed.
  147.       OutName: Filename of destination file to hold compressed data.
  148.  
  149.    Returns:
  150.       LZH_OK if no errors or error code listed above.
  151.  
  152. *--------------------------------------------------------------------------*
  153.  
  154. int FAR PASCAL Decompress( LPSTR InName, LPSTR OutName )
  155.    Decompresses data from source file, writing results to destination.
  156.  
  157.    Parameters:
  158.       InName:  Filename of source file containing compressed data.
  159.       OutName: Filename of destination file to receive decompressed data.
  160.  
  161.    Returns:
  162.       LZH_OK if no errors or error code listed above.
  163.  
  164. *--------------------------------------------------------------------------*
  165.  
  166. int FAR PASCAL AppendFile( LPSTR lpTarget, LPSTR lpFile2 )
  167.    Adds a file to the back of another file.
  168.  
  169.    Parameters:
  170.       lpTarget: First source filename. This file receives the second file.
  171.       lpFile2:  Second source filename. This is added to the first file.
  172.  
  173.    Returns:
  174.       LZH_OK if no errors or error code listed above.
  175.  
  176.    Notes:
  177.       lpTarget MUST be a valid file. If the filename specified is not found,
  178.       it is NOT created. The second file specified is added the end of the
  179.       first, but is not deleted.
  180.  
  181. *--------------------------------------------------------------------------*
  182.  
  183. int FAR PASCAL DeleteFile( LPSTR Filename )
  184.    Deletes file(s) specified by filename. You may use wildcard characters.
  185.  
  186.    Parameters:
  187.       Filename: Name of the file to be deleted from disk.
  188.  
  189.    Returns:
  190.       LZH_OK if no errors or error code listed above.
  191.  
  192. *--------------------------------------------------------------------------*
  193.  
  194. long FAR PASCAL GetFileSize( LPSTR Filename )
  195.    Obtains the byte size of a file.
  196.  
  197.    Parameters:
  198.       Filename: Name of file to find the size of.
  199.  
  200.    Returns:
  201.       0 if file not found or file size as a 4 byte long value.
  202.  
  203. *--------------------------------------------------------------------------*
  204.  
  205. int FAR PASCAL CopyFile( LPSTR Source, LPSTR Dest )
  206.    Copies a source file to a destination file.
  207.  
  208.    Parameters:
  209.       Source: Filename of fie to be copied.      
  210.       Dest:   Filename to be created and copied to.
  211.  
  212.    Returns:
  213.       LZH_OK if no errors or error code listed above.
  214.  
  215.    Notes:
  216.       The source file is NOT deleted.
  217.  
  218. *--------------------------------------------------------------------------*
  219.  
  220. DWORD FAR PASCAL GetFreeDiskSpace( LPSTR lpDrv )
  221.    Finds the amount of free disk space in bytes.
  222.  
  223.    Parameters:
  224.       lpDrv: NULL terminated string containing drive letter to check.
  225.  
  226.    Returns:
  227.       0 if an error occurred or bytes free on given disk.
  228.  
  229.    Notes:
  230.       Only the first character in the string is actually worked on. The rest
  231.       of the string is ignored. To obtain the size of the default (current)
  232.       disk, make the first character ASCII 64.
  233.  
  234. *--------------------------------------------------------------------------*
  235.  
  236. int FAR PASCAL SetFileStatus( LPSTR Filename, int Status )
  237.    Sets status of file.
  238.  
  239.    Parameters:
  240.       Filename: Name of file to change the status of.
  241.       Status:   Attribute bits. Use LZH constants listed above.
  242.  
  243.    Returns:
  244.       LZH_OK if no errors or error code listed above.
  245.  
  246.    Notes:
  247.       Attribute constants are LZH_READONLY, LZH_HIDDEN and LZH_SYSTEM.
  248.  
  249.  
  250.